OLE In-Place Activation
Volume Number: 11
Issue Number: 1
Column Tag: Microsoft Technology
In-Place Activation with OLE 
Select, modify, and manipulate, all without leaving the application.
by Michael Fanning, Microsoft
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
This article is the second in a series describing the evolution of a simple OLE2 object
server and will show you how to implement the Visual Editing feature of OLE for the
Macintosh. A general familiarity with OLE and its underlying architecture (the
Common Object Model, or COM) is assumed, a passing familiarity with the OLE
interfaces for embedding OLE objects would be helpful. At a minimum, I’d suggest
reading the first article which examines a simple (non-in-place) object server and
also has a nifty glossary of essential OLE terms and concepts. If you haven’t read it,
don’t have a copy, are uncertain of what OLE is and/or have used the word more often at
bullfights than in technical discussions, don’t worry; we’ve included it on a CD that’s
bound into this magazine. In fact, the CD holds the entire OLE for the Macintosh
Software Developer’s Kit in its final form, for both 68K and Power Macintosh. The
only thing that could possibly make it easier to implement Visual Editing in your own
code would be a roadmap in the form of commented pseudo-code drawn from a working
in-place server.
Goal
Back in the August issue, the editorial page predicted readers would find the piece
“more pleasant than dissecting a frog” - I thought this was generous, ‘equally
pleasant’ was probably sufficient - “and at least as instructional”. I sincerely hope
this last goal was met, dissection can set a high standard on information returned
weighed against effort put forward. I’d be more comfortable if there was more life in
the imagery, realistically the comparison turns to vivisection at that point, so let’s
stick with the dissection metaphor and sharpen up the code scalpels.
OK, onwards.
Customers.
Visual Editing, also known as in-place activation, is the feature of OLE that customers
care about the most. It’s what allows them to edit any kind of data in any kind of
document; to them, that’s what OLE is. Dissecting the implementation of an in-place
server doesn’t spark much interest, that’s best left to people my younger sister
always describes to me as ‘kinda geeky, like you’. Visual Editing is without question
the most important user interface feature that’s defined by the OLE specification.
In-Place, Defined
In-place activation is a user interface standard by which an object can be selected,
modified, and generally manipulated by the user, all while appearing to remain within
the application which contains it. The object provides the functionality, the container
provides the visual context. The editable state of the object is evident in certain user
interface (UI) clues: a composite menu bar that contains both server and container
menus, server toolbars or floating windows that appear on activation, and a shaded or
hatched border which surrounds an in-place active object, grow handles optional. The
net UI illusion is that an embedded object’s data is modified without (apparently)
leaving the container application. Instead, the server’s functionality is brought into
the container’s context, reinforcing a notion that the user’s document is central and
that each kind of data in the document should be seamlessly editable without the user
needing to worry about which application to invoke.
One of the Macintosh OLE developers compares the process to implementing a kind
of “well-defined” dialog. The container provides a context which it describes to the
server. The server provides a service, or feature, including the UI. Cooperative
communication between the apps according to a protocol defined in OLE allows the
server’s UI and feature to blend seamlessly into the container’s context.
Com, Redux, Revisited, In Short, Re-revealed
Before continuing I’d like to review the basic ideas which comprise the Common Object
Model, and therefore OLE itself. If you haven’t grabbed the first article from the CD
for a read-through, you should. It’s one of those, grab-your-nose,
it’s-got-to-go-down-at-some-point and
it-may-as-well-be-sooner-rather-than-later, cod-liver oil kind of articles.
Anyone who’s inclined to skip past a COM/OLE recapitulation can look ahead for the
next reference to in-place in bold caps.
OLE0 - a set of interfaces which define essential protocols for
interoperability.
Interface 0 - a table (or vtable) of function pointers to constituent
routines, commonly known as methods.
Method 0 - a member function of an interface.
There are specific interfaces for each of the general areas of functionality OLE defines;
they include Uniform Data Transfer, Linking (Naming and Binding), Embedded Objects
(Compound Document Management), Drag and Drop, Visual Editing, Automation
(Programmability), and Structured Storage (disk- and memory-based persistent
storage). Inter-object communication is facilitated by notification and
concurrency-related interfaces.
OLE is the protocol, COM is the means
COM itself can be reduced to a small set of simple and powerful concepts which
are the quantum building blocks of OLE. Essentially, the Common Object Model defines
how objects should interact, both in the context of a single application (as an
in-process server or object handler on Power Macintosh) and across application
boundaries. While OLE defines specific protocols of communication, COM provides the
means and supporting mechanism which allows transparent communication between
applications.
What this means is that a user of an object (i.e., the one calling an interface
method) doesn’t need to know where the code that’s called exists. It might be
in-process, or in a separate background application. In the near future, it might
reside across the network or be running in a different operating system altogether.
The client is completely insulated from any concerns related to how the call makes it to
the server and how the result makes it back.
COM Concerns
The basic contract for a COM object or its client is not particularly demanding. 1)
COM applications follow a convention for retrieving and/or providing pointers to their
supported objects known as interface negotiation, a simple idea which yields powerful
returns. 2) COM defines a set of rules and methods which guarantee the lifetime of an
object while it is in use by any COM client.
Interfaces and their Negotiation - Strictly speaking, interfaces are
nothing more than abstract base classes comprised of pure virtual member functions.
This basically means that the member functions are defined by OLE without providing
any implementation. COM objects derive from the supported interface and implement
all its methods, without exception.
After retrieving the initial pointer to an object (which is really just a pointer to
one of the interfaces the object implements), pointers to different interfaces
(representing different functionality) also implemented by the object can be retrieved
through interface negotiation (IUnknown::QueryInterface).
Object Lifetime - COM defines a method for incrementing an object’s
reference count (IUnknown::AddRef) and a method for decrementing it
(IUnknown::Release). All objects ultimately derive from IUnknown and therefore
must implement these two methods. An object increments its own reference count
whenever it hands out a pointer to one of its interfaces (usually in response to
QueryInterface). When the code that requested the interface is done with it, it calls the
object’s Release method which decrements the object’s reference count. If the
reference count drops to zero, that indicates that no one is using the object and it can
safely delete itself. This simple set of rules allows an object to track how long it needs
to exist since it always knows how many clients still have a reference to one of its
interfaces.
Interface negotiation and reference counting are provided through a
single interface, IUnknown, which serves as the base class for all COM objects. These
two concepts are basic to COM and a good place to start gaining a general understanding.
COM addresses other subjects that are beyond the scope of this article:
• Identification (Globally Unique Identifiers)
• Memory Allocation/Deallocation
• Error and Status reporting
• Location/Dynamic Loading/Reuse of Object Code
• Security/Encapsulation
• Remoting
The glossary in the August MacTech article covers some of these topics in greater
detail.
Hold On, I Know There’s Something About
In-Place In Here Somewhere
Subsequent sections of this article will cover the following, in order:
1. The OLE Interfaces specific to in-place capable servers
2. The series of calls between a container and server which result in an embedded
object
3. The basic sequence of steps for activating an object in-place
4. A list of possible OLE object states and definitions
5. A pointer to the activation logic used by SimpleIPServer, in pseudo-code
6. Exit
Item #5 (and the SimpleIPServer source) is payoff for anyone looking for a leg up
implementing visual editing in an object server. The logic in this pseudo-code is a
clear roadmap for activating objects in-place on the Macintosh. I’ll upload a similar
file detailing deactivation/close logic to the MS BBS on AppleLink and to the Macintosh
library (lib 12) of the MS OLE forum on CompuServe (GO WINOBJ) in the not too
distant future.
Visual Editing in Two Easy Interfaces + Assorted Logic
The server-side of in-place editing is limited to two interfaces, IOleInPlaceObject and
IOleInPlaceActiveObject, which define 4 and 5 unique methods, respectively. Both
interfaces derive (as all in-place interfaces do) from IOleWindow, which itself has